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BCOnexus 


BCOnexus is an platform-free open-source application, delivered as a Docker image, presents a 
interactive web service for importing, editing, and exporting BioCompute Objects (BCO), a 
framework for standardizing and sharing computations and analyses generated from High- 


throughput sequencing. 


BCOnexus can be launched locally on any platform supporting execution of Docker images, and 


can be accessed from any web browser using a non-standard port. 


MultiSampleSmartSeq2_v 


dxCompiler 
@) vanes 


MultiSampleSmartSeq2_v4.wdl 


BCOnexus will interact with the local file system, supports the uploading of WDL, CWL, and Json 
files, downloading, and publishing BCO files. BCOnexus can interact with the DNAnexus platform 
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via its API to ingest native workflow metadata into BCOs and to create native workflows 
from WDL and CWL scripts. 


The application now supports users to compare BCOs, export BCO as a new format (Markdown) 


and can interact with the precisionFDA to upload the BCO directly to it. 
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Setup and Install 


1. Install docker on your local machine. 


Install Docker Desktop on Linux 


Install Docker Desktop on Mac 


Install Docker Desktop on Windows 


2. Download the latest BCOnexus docker image from Dockerhub. 


docker pull beodocker/bconexus| 


| Commented [1]: may change if the bconexus image 
' location in dockerhub change 


3. Open the terminal or command line application and run the below commands 


docker run --platform=linux/arm64 -it -p 8600:8080 bconexus: latest 


4. Open any browser and enter the URL: http://127.0.0.1:8000/index and the BCOnexus home 
web page will be displayed. 
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BCOnexus Build JSON Editor JSON Compare Review Export > Search keys 3 


bco 


@ Feedback [ © Raise Github Issue 
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Load new workflow file 


1. Click on Source circle on the home page. 

2. Select workflow type as BCO and click on the “Choose Fife’ button to select a 
<bco_name>,json file. 

3. Click on the Load button to load the <bco_name>.json file into the Editor, then the user 


can edit the BCO Json file. 


Upload Your File 


Select Workflow Type:| | CO 


Select Workflow File: lo file chosen 
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Update BCO with workflow files 


1. To update the in-memory bco with a WDL/CWL workflow, click on the Source circle on the 
home page. 

2. Select workflow type as WDL/CWL and select the respective .wdl/.cwl file by clicking on 
the “Choose File” button. 

3. Click on the Update button to update the in-memory BCO json file with the information 
from the WDL/CWL workflow. 


Upload Your File 


Select Workflow Type: WDL 


Select Workflow File: |! Choose File |No file chosen 


ac 
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Update BCO with DNAnexus workflow files 


1. To update the in-memory bco with a DNAnexus workflow (for which you will need a 


DNAnexus access_token; refer to the manual section Get DNAnexus token), select 


workflow type as DNAnexus Workflow and click on Get Projects. 


Upload Your File 


Select Workflow Type: | DNAnexus Workflow > 


Get Projects 


2. If there is no active DNAnexus token available, the user will be prompted with an alert to 
provide a DNAnexus access token. Paste the access_token in the field and click on Get 


Projects. 
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Upload Your File 


Select Workflow Type: | DNAnexus Workflow 


DNAnexus access token 


3. Select a DNAnexus project, workflow and analysis from the drop downs and click on the 


Update button to update the in-memory bco.json file with the DNAnexus workflow. 
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DNAnexus’ 


Upload Your File 


Select Workflow Type: | DNAnexus Workflow 


Select Project: 


Select Workflow: test_workflow 


Select Analysis: some_workflow 


CONFIDENTIAL | 10 


Reset BCO 


Click on the Source circle on the home page and click on the Reset button to clear the currently 


editing BCO json file. 


Upload Your File 


Select Workflow Type: | WoL 


Select Workflow File: | Choose File | No file chosen 
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Build BCO 


The BCO json file can be edited domain-wise by clicking on the respective domain circle on the 


homescreen. 


Example: 


To edit the “description domain”, click on the “description” circle on the homescreen. The below 


screen will be displayed. 


Click on the b> for pipeline_steps to view and edit the description_domain.pipeline_steps. 


BCOnexus Build 


bco. description_domain. pipeline_steps 


@ =] e. step_number 


DNAnexus: 


BCOnexus Build = JSON Editor 
bco. description_domain 
eo > 1) 
= @ee@ >» 
‘S Lao) 


(bs) 


JSON Editor 


JSON Compare 


keywords 


xref 


platform 


pipeline_steps 


JSON Compare 


name 


makeblastdb 


blastn 


Review Export Search keys 
[items] 
[mamespace, name, [ids], access_time] 
[items] 
[step_number, name, description, version, [prerequisite], [input_list], _ [output_list]] 
Review Export Search keys 
description version prerequisite input_list output_list 
Make blast database Nucleotide-Nucleotide BLAST 2.1.0+ > o > 1 > 3 
Run nucleotide blast 13 > o > 4 > 1 
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=a 
Click on a field to make the field editable. You may update the value for the field, and 


then click or use the tab key to move to the next field. 


BCOnexus Build ~~ JSONEditor ~~ JSONCompare Review —Export ~ Search keys 
bco. description_domain. pipeline_steps 


prerequisite input_list output_list 


=) 8 ‘ e. step_number name description version 


=e @@e 1 
@ o® 2 blastn Run nucleotide blast 43 > o > 4 D> 1 


Make blast database —Nucleotide-Nucleotide BLAST 2.11.0+ > o > 1 > 3 
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1. Add new row to the BCO 


To add a new row, click on the Add Row button. 


Review Export Search keys 


BCOnexus Build JSON Editor JSON Compare 


bco. description_domain. pipeline_steps 


Pg Se A step_number name description version prerequisite input_list output_list 
“ote 1 Make blast database —Nucleotide-Nucleotide BLAST 2.11.0+ > o > 1 > 3 
“@ g 2 blastn Run nucleotide blast 13 > o > an 1 


JSON Compare Review ~—Export Search keys 


BCOnexus Build =~ JSON Editor 


co. description_domain. pipeline_steps 


step_number name description version prerequisite input_list output_list 
1 makeblastdb Make blast database —_Nucleotide-Nucleotide BLAST 2.11.0+ > o > 1 > 3 
13 > o > 4 > 1 


Zz blastn Run nucleotide blast 
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2. Delete a row from the BCO 


To delete a row, make sure all fields in the row are updated with an empty value and go back to 
the previous screen and come back to the same screen. You may also refresh the screen once 


all fields are blank/empty. 


BCOnexus Build ~~ JSONEditor ~~ JSONCompare Review —Export Search keys 


co. description_domain.pipeline_steps 


e step_number name description version prerequisite input_list output_list 


1 makeblastdb Make blast database —_Nucleotide-Nucleotide BLAST 2.11.0+ > o > 1 > 3 


e 
dl 2 


blastn Run nucleotide blast 13 > o > 4 > i 


BCOnexus Build ~~ JSONEditor ~~ JSONCompare Review —Export Search keys 


bco. description_domain.pipeline_steps 


e° e step_number name description version prerequisite input_list output_list 
@ e e 1 makeblastdb — Make blast database —Nucleotide-Nucleotide BLAST 2.11.0+ > o > 1 > 3 
©. © 2 blastn Run nucleotide blast 13 > o > 4 > 1 
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Search 


The search bar in the upper right corner will search the current BCO file for the specified keyword 


and display the screen with first matching result 


BCOnexus Build += JSON Editor. += JSONCompare = Review ~—Export~ pipeline_steps 


bco. description_domain (pipeline_steps 


S eS e step_number name description version prerequisite input_list output_list 
@ e @. 1 makeblastdb Make blast database —-Nucleotide-Nucleotide BLAST 2.11.0+ > o > 1 > 3 
. @ @ 2 blastn Run nucleotide blast 13 > o > a > 1 
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Edit with the JSON Editor 


To edit a BCO in JSON format, navigate to the JSON Editor tab. 


Click Edit to make changes, use Beautify to format the code, and then click Save to preserve 


your modifications. After saving, click Validate to check the file's integrity; a green checkmark 


indicates a valid file, while a red cross signifies errors. 


BCOnexus Build JSON Compare Review Export » 


beo 


JSON Editor 
{ 


homologs json", 
"'spec_version": "https:/)W3id.org/ieee/ieee-2791-schema/279 object json", 
"etag™: "f37a6806e8e5979b3e1527af258d196a4af116247727f8dladsbf2ba6173bece", 
"provenance_domain": { 
“name: "HCV1a BLASTN homologue identification, with collapsed secondary files.", 
"version": "1.0", 
"review": [ 


"email": "", 
contribution”: [], 
"orcid": " 


7 
"reviewer_comment": "", 
gtatus": 

i 
1, 


"derived_from": "https://github.com/Hadleyking/bco-tool/1.1.0/tests/ewl-blastn-homologs,json", 


"obsolete_after": "2118-09-26714:43:43-0400", 
"embargo": { 
"start_time": "2021-08-13T10:45:22-0500", 
"end_time": "2021-08-13T10:45:22-0500" 
h 


DNAnexus’ 


“object_id": "https://raw.githubusercontent.com/HadleyKing/bco-tool/1.1.0/tests/collapsed-cwl-blastn- 


Beautify 


Save 


Validate 


searchin [owe ] 
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Compare BCOs 


To compare BCOs, select the JSON Compare tab. Click Upload to compare to open a modal 
where you can choose a second BCO (CWL, WDL, JSON, or workflow from DNAnexus) to 


compare against the currently editing BCO in memory. 


BCOnexus Build = JSONEditor_ | JSONCompare | Review — Export Search keys 


bo 


Upload file to compare 


Please upload second BCO file for comparison 


The upload process for the comparison file mirrors the BCO file upload steps outlined in the 


previous section. 


Upload The 2nd BCO 


Select Workflow Type: | WDL 


Select Workflow File: | Choose File | No file chosen 


Once the second BCO is uploaded, both files will be displayed side-by-side for easy comparison. 
Any modifications made to the open BCO within the editor tab will be reflected in real-time on 


the comparison view. 
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"reviewer_comment": 


"status": "" 


Review 


es 
BCOnexus Build += JSONEditor + JSON Compare 
bco 
® Currently in Editor BCO 
ea 1,411 @@ 
1 ie 
2)- “object_id": " 
3\)- “spec_version" ittps: //w3id.org/ieee/ieee-2791-schema, 
4 = “etag": "#37a6806@0859: #2564 tS6RaaTLA6747707¢ 
J “provenance_domain": { 
e| = 
7\- "version": "1.6", 
8 "review": [ 
J { 
10 "date": 
il “reviewer 
i 
13 ffiliation": "", 
1 “email 
5 "contribution": [, 
16 “orcid": "" 
v7 h 
i 
1 


Export Search keys Search 


Upload file to compare } 


JSON Compare 


& biocompute_example.json 


"provenance_domain": { 


"ane": *HCVia BLASTN Ronotogue identification, With collapsed Secondary fitesi",| © + “mane: “CVia NEGIpBEVAT FesiStance SWF detection”, 


+ "version": "2.9", 
8 "review": [ 
Ss { 
16 "date": "" 
ul "reviewer" 


i “name's, 
ffiliation": *", 


19 "status": *" 


"date": 
“reviewer_comment": "Approved by research institution staff. Waiting for a 
"status": “unreviewed”, 
"reviewer": { 

"name": "Charles Darwin", 

"affiliation": "HS Beagle", 

"email": "name@example.edu", 

“contribution: [ 


epeeeetree 


To compare with another BCO, simply repeat the file upload process for the second BCO. 


Note: The program will also validate the comparison BCO and will notify the user if it is not valid. 


BCOnexus 


beo 


DNAnexus’ 


Build 


JSON Editor 


JSON Compare 


Revie 


localhost:8000 says Search keys Search 


Note: The uploaded file did not pass validation 


Upload file to compare 


Please upload second BCO file for comparison 
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Review BCO 


Clicking on the Review tab will validate the in-memory BCO as per the schema, and produces 


domain-wise error messages on the right side under validation. Clicking on the message will 


expand the bco.json tree on the left to the point of error and will highlight the errored field. 


© localhost 


BCOnexus Build = JSON Editor 


bco 


Object Information 
2791 Object - 


spec_version: 


etag: 


usability domain + 
parametric domain + 
io domain + 

error domain + 
execution domain + 
description domain + 
provenance domain + 


DNAnexus’ 


JSON Compare =e 


Validation 
2791 Object 


Fail 
object_idis empty] spec_versionis empty __etag is empty 
Fail 
usability domain is empty 
Error domain 
Fail 
error_domain is empty empirical_error is empty 
algorithmic_error is empty 
4 “ 
Fail 


parametric domain is empty 
10 domain 
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Export BCO 


BCOnexus provides many ways to export the current BCO loaded in working memory, either to a 


local system or to an external repository. 


1. Download BCO to local storage 


Click on the Export dropdown and select BCO File option to download the in-memory BCO. 


BCOnexus Build ~~ JSONEditor ~~ JSONCompare —_—Review Search keys 


DNAexus Workflow 


BCO Repository 
® precisionFDA 7 @ 
Custom BCO database 
i _ } - 3 
& g 


eaFeedback | | € Raise Github Issue 
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Download BCO File 


BCOName | (8CO name ) 


Provide a name for the file in the prompt and click on the Download BCO button to download the 


file. 


a) Test_BCO.json 
1 3 - Done 
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2. Export BCO file to a DNAnexus project 


Click on the Export menu dropdown and select the DNAnexus Workflow option to export the 


BCO file to a DNAnexus project. 


Provide a name for the file in the prompt and click on the Get Projects button to fetch all the 
projects. If there is no active token, you will be prompted with an alert to provide a token, 


obtainable on the DNAnexus Platform. 


Export BCO to DNAnexus Workflow 


Get Projects 


Close Upload to DNAnexus 


BCO Name BCO name 
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DNAnexus access token 


Provide a valid token to fetch the projects from DNAnexus to which you may upload the BCO file. 
Select a project from the available list of projects and click on the | button 


to upload. 


Export BCO to DNAnexus Workflow 


Select Project: VNBE 
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3. Export BCO file to the BCO Repository 


Click on the Export dropdown in the top menu and select the BCO Repository option to export 
the in-memory BCO file to a BCO Repository. 


Provide the BCO DB URL, Prefix, Owner Group, and User token, and then click on Submit to 
upload the object to the BCO Repository. 


Export to BCO DB 


BCO DB URL (https:/biocomputeobject.org/api/objects/draft) 


Prefix [DNAN 


Owner Group | (bco_drafter ) 


UserToken |(isertoken SS~=~—~‘~SCS 
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4. Export BCO file to precisionFDA platform 


Click on the Export menu dropdown and select the precisionFDA option to export the in-memory 


BCO file to a precisionFDA platform. 


Provide a name for the file in the prompt and click on the Get Spaces button to fetch all the 
spaces. If there is no active token, you will be prompted with an alert to provide a token, 


obtainable on the precisionFDA Platform. 


Export BCO to precisionFDA 


Upload to precisionFDA 
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[PFDA access token 


Provide a valid token to fetch the spaces and folders from the precisionFDA to upload the BCO 
file. Select a project and a folder in the project from the available list of projects and click on the 


button to upload. 


Export BCO to precisionFDA 


Select Space: | BCO_export (Private) 


Select Folder: | 
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5. Export BCO file to Custom BCO Database 


Click on the Export dropdown in the top menu and select the Custom BCO Database option to 


export the in-memory BCO file to a Custom BCO Database. 


Provide the BCO DB URL, add Credentials key and value, and then click on Submit to upload the 
object to the Custom BCO Database. 


Custom BCO database 


BCO DB URL url 


Credentials 
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6. Export BCO to Markdown file 


Click on the Export dropdown and select BCO Markdown File option to convert BCO from json 


format to markdown and download BCO. 


Export BCO as Markdown File 


Provide a name for the file in the prompt and click on the Download button to download the file. 
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HCV1a test BLASTN homologue identification, with collapsed secondary files. 


Object ID: https://raw.githubusercontent.com/HadleyKing/bco-too/1.1.0/tests/collapsed-cwl-blastn-bao-homologs.json 
‘Spec Version: https://w3id.org/iese/ieee-2791-schema/2791objectjson| 
etag: £87a6806e8e5979b3e1527af258d!96adall 1624772718d1 ad8bf2ba6173bece 


Usability 


Run blastn to identify homologs. This is an essentual ‘Hello, World!" for bioinformatics. The input file is a HCV 1a isolate H77 complete genome [taxid:63746] (nucinput fa) nucleotide sequence. The database 
(nucdb.fa) is a collection of HCV sequences. 

Step 1. Make blast database: makeblastdb -in nucdb.fa -dbtype nucl, 

Step 3. Run nucleotide blast blastn -db nucdb.fa -query nucinput.fa -out result. 


Description 


Keywords 


HCV1a, Common Workflow Language, BLASTN, homologue 


External References 


Name Namespace Access Time 
Taxonomy taxonomy —_—Frriday 15, January 2021 


ENA ena.embl Friday 15, January 2021 M67463.1 
Platform 
CWL 
Pipeline Steps 
Step 1: makeblastdb 
Version: Nucleotide-Nucleotide BLAST 2.11.0+ 


Description: Make blest database 
Prerequisites 


The export file will meet the standard conversion requirements of the BCO Markdowrn file. 
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Get DNAnexus token 


Prerequisite: 


You will need to have a DNAnexus Platform account on hitps://platform.dnanexus.com/. 


Steps to generate a DNAnexus access token: 


1. Log in to the DNAnexus platform. 


€ > Cf platformdnanexusconviogin er One: 


DNAnexus: 


Log in to Your Account 


Username or Email 


Create an Account 
Forgot your password? 


2. Click on the user icon on the right and select “My Profile” from the options. 


© FP So @ platformdnanenus.com/panx/projects 


= DNAnexus *orrs- too ete 2-@- 
pines i ee 
ating 
AyNeme~ = AY Aey Creator ~ Ay Shared Win ~ 
Account Security 
Name Data Usage Access ¥ Members Modified Tags o 
Sign Ot 
@_ Mitti-sarnple Smart-Soq? 91.9GiB Admin 6 80/2021 4:29 PM 
A atin 7.52 MiB ‘Admin 4 2rare0e2 11:29PM 
@ sudheer 08 Admin 


1 Sv2a/2022 10:24 PM 


616.89 KB Admin 3 7/28/2022 7:19 PM 


3. Click on API TOKENS. 
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€ > Ce platformdnanenus comvpanx/profile/sudheer/settings/userAccount — er O26: 
= DNAnexus’ P®urcrs- — roos HELP ~ Av — 
© sudheer Naidu Sirasapalli USERACCOUNT BILLING = ACCOUNTSECURITY API TOKENS 
| ACCOUNT INFO Account Info 

EMAIL 

Username sucreor 
PASSWORD 
PLATFORM PREFERENCES First Name Sucheer é 


4. Click on New Token, if you do not have an existing one. 


€ > Ge platformadnanexuscom/profile/sudhwer/tokers er On a@: 


= DNAnexus: "orcts-  roois- aur 2. @- 


Sudheer Naidu Sirasapalli ser account illing Account _AP| Tokens 


ja} Token Label Expiration Date * Project Permissions 


5. Enter a token Label, select the Token Scope, set the Expiration Date, and then enter your 


DNAnexus account Password. Click on Generate Token. Once generated, you should save 


the token. 
€ > CS @ photiormdnanenss.com/profile/sudheer/tokens er Ore: 


x 
& NEW TOKEN 


se. [abet for your toten, € g. “My Sequer 
TOKEN SOME @ Al projects © Selected projects 
“All projects” tokens wall have access to PHI data 
ORATION DATE Od-mm-yyyy (- eo ° 


‘Tokens will expire in one month if no date ts given 
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Questions 


If you have any questions, please feel free to contact us at support@dnanexus.com. Please make 


sure to communicate that you have questions about the BCOnexus Platform-Free Editor. 
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